# Configure Rslib

Rslib's configuration is based on Rsbuild, which means that you can use all of Rsbuild configurations, as well as the `lib` configuration specific to Rslib.

## Configuration structure

Rslib provides the `lib` option to configure the library outputs. It is an array, and each object is used to describe a format of the output.

For example, output ESM and CJS formats, and use `es2021` syntax:

```js title="rslib.config.mjs"
export default {
  lib: [
    { format: 'esm', syntax: 'es2021' },
    { format: 'cjs', syntax: 'es2021' },
  ],
};
```

### Common Rsbuild configurations

You can set common Rsbuild configurations outside the `lib` field, which will be inherited by each configuration object inside the `lib` field.

For example, set the [output.target](/config/rsbuild/output#outputtarget) of Rsbuild to `web`, which will affect the output of all `lib` configuration objects:

```js title="rslib.config.mjs"
export default {
  lib: [
    { format: 'esm', syntax: 'es2021' },
    { format: 'cjs', syntax: 'es2021' },
  ],
  output: {
    target: 'web',
  },
};
```

### Separate Rsbuild configurations

In the `lib` field, you can set separate Rsbuild configurations for each output format, which will override the common Rsbuild configurations outside the `lib` field.

For example, separately set the [output.target](/config/rsbuild/output#outputtarget) of the ESM output to `web`:

```js title="rslib.config.mjs"
export default {
  lib: [
    // The target of the ESM output is `web`
    {
      format: 'esm',
      output: {
        target: 'web',
      },
    },
    // The CJS output inherits the common configuration and target is `node`
    {
      format: 'cjs',
    },
  ],
  output: {
    target: 'node',
  },
};
```

Rslib will generate the [environments](https://rsbuild.rs/config/environments) configuration of Rsbuild internally, you can run [rslib inspect](/guide/basic/cli#rslib-inspect) command to view the final generated configuration.

You can also refer to the [Configuration Overview](/config/) page to view the detailed introduction of all configurations.

## Configuration file

When you use the CLI of Rslib, Rslib will automatically read the configuration file in the root directory of the current project and resolve it in the following order:

- `rslib.config.mjs`
- `rslib.config.ts`
- `rslib.config.js`
- `rslib.config.cjs`
- `rslib.config.mts`
- `rslib.config.cts`

We recommend using the `.mjs` or `.ts` format for the configuration file and importing the `defineConfig` utility function from `@rslib/core`. It provides friendly TypeScript type hints and autocompletion, which can help you avoid errors in the configuration.

For example, in `rslib.config.ts`, you can define the Rslib [syntax](/config/lib/syntax) configuration and the Rsbuild [output.target](https://rsbuild.rs/config/output/target#outputtarget) configuration:

```ts title="rslib.config.ts"
import { defineConfig } from '@rslib/core';

export default defineConfig({
  lib: [
    {
      format: 'esm',
      syntax: 'es2021',
    },
  ],
  output: {
    target: 'node',
  },
});
```

If you are developing a non-TypeScript project, you can use the `.mjs` format for the configuration file.

:::tip

When you use the `.ts`, `.mts`, and `.cts` extensions, Rslib will use [jiti](https://github.com/unjs/jiti) to load configuration files, providing interoperability between ESM and CommonJS. The behavior of module resolution differs slightly from the native behavior of Node.js.

:::

## Specify config file

Rslib CLI uses the `--config` option to specify the config file, which can be set to a relative path or an absolute path.

For example, if you need to use the `rslib.prod.config.mjs` file when running `build`, you can add the following scripts to `package.json`:

```json title="package.json"
{
  "scripts": {
    "build": "rslib build --config rslib.prod.config.mjs"
  }
}
```

You can also abbreviate the `--config` option to `-c`:

```bash
rslib build -c rslib.prod.config.mjs
```

## Specify config loader

Rslib provides three ways to load configuration files:

- `jiti`: When you use a configuration file with the `.ts`, `.mts`, and `.cts` extensions, Rslib will use [jiti](https://github.com/unjs/jiti) to load configuration files, providing interoperability between ESM and CommonJS. The behavior of module resolution differs slightly from the native behavior of Node.js.
- `native`: Use Node.js native loader to load the configuration file. This can ensure that the module resolution behavior is consistent with the native behavior of Node.js and has better performance. This requires that your JavaScript runtime already natively supports TypeScript.

  For example, Node.js v22.6.0+ already natively supports TypeScript, you can use the following command to use the Node.js native loader to load the configuration file:

  ```bash
  # Node.js >= v22.18.0
  # No need to set --experimental-strip-types
  npx rslib build --config-loader native

  # Node.js v22.6.0 - v22.17.1
  # Need to set --experimental-strip-types
  NODE_OPTIONS="--experimental-strip-types" npx rslib build --config-loader native
  ```

- `auto`(Default): Use Node.js's native loader to load configuration files first, fallback to using jiti if it fails.

### About Node.js native loader

When using Node.js's native loader, please note the following limitations:

1. When importing JSON files, you need to use import attributes:

   ```ts
   import pkgJson from './package.json' with { type: 'json' }; // ✅ Correct
   import pkgJson from './package.json'; // ❌ Incorrect
   ```

2. When importing TypeScript files, you need to include the `.ts` extension:

   ```ts
   import baseConfig from './rslib.base.config.ts'; // ✅ Correct
   import baseConfig from './rslib.base.config'; // ❌ Incorrect
   ```

> See [Node.js - Running TypeScript Natively](https://nodejs.org/en/learn/typescript/run-natively#running-typescript-natively) for more details.

## Using environment variables

In the configuration file, you can use Node.js environment variables to dynamically set different configurations:

```ts title="rslib.config.ts"
import { defineConfig } from '@rslib/core';

export default defineConfig({
  lib: [
    {
      format: 'esm',
    },
  ],
  source: {
    alias: {
      '@language':
        process.env.LANGUAGE === 'en'
          ? './src/language/en.js'
          : './src/language/zh.js',
    },
  },
});
```

## Configure Rsbuild

Rslib allows you to use most of the Rsbuild configurations. Currently, the `environments` config is not supported because it is generated internally by Rslib.

- Refer to [Rsbuild Configuration](/config/rsbuild/) for common Rsbuild configurations.
- Refer to [Rsbuild Documentation](https://rsbuild.rs/config/index#config-overview) for all Rsbuild configurations.

## Configure Rspack

Rslib is built on top of Rsbuild and Rsbuild supports directly modifying the Rspack configuration object and also supports modifying the built-in Rspack configuration of Rsbuild through `rspack-chain`. This means you can configure Rspack related configurations in an Rslib project as well.

For more details, refer to [Configure Rspack](https://rsbuild.rs/guide/basic/configure-rspack).

## Debug mode

You can add the `DEBUG=rsbuild` environment variable when building to enable Rslib's debug mode.

```bash
DEBUG=rsbuild pnpm build
```

In debug mode, Rslib will output additional log information and write the final Rsbuild config and Rspack config after processing by Rslib to the output directory, making it convenient for developers to view and debug.

Here is an example of a library that sets both CJS and ESM formats:

```
Inspect config succeed, open following files to view the content:

  - Rsbuild Config (esm): /project/dist/.rsbuild/rsbuild.config.esm.mjs
  - Rsbuild Config (cjs): /project/dist/.rsbuild/rsbuild.config.cjs.mjs
  - Rspack Config (esm): /project/dist/.rsbuild/rspack.config.esm.mjs
  - Rspack Config (cjs): /project/dist/.rsbuild/rspack.config.cjs.mjs
```

- Open the generated `/dist/.rsbuild/rsbuild.config.esm.mjs` file to see the complete content of the Rsbuild config.
- Open the generated `/dist/.rsbuild/rspack.config.esm.mjs` file to see the complete content of the Rspack config.

::: info
If you want to view the normalized Rslib configuration, you can add the `DEBUG=rslib` environment variable when building or run the [rslib inspect](/guide/basic/cli#rslib-inspect) command.
:::
